Crate mockito

Expand description

Mockito is a library for generating and delivering HTTP mocks in Rust. You can use it for integration testing or offline work. Mockito runs a local pool of HTTP servers which create, deliver and remove the mocks.

Features

Supports HTTP1/2
Runs your tests in parallel
Comes with a wide range of request matchers (Regex, JSON, query parameters etc.)
Checks that a mock was called (spy)
Mocks multiple hosts at the same time
Exposes sync and async interfaces
Prints out the last unmatched request in case of errors
Simple, intuitive API
An awesome logo

Getting Started

Add mockito to your Cargo.toml and start mocking:

#[cfg(test)]
mod tests {
  #[test]
  fn test_something() {
    // Request a new server from the pool
    let mut server = mockito::Server::new();

    // Use one of these addresses to configure your client
    let host = server.host_with_port();
    let url = server.url();

    // Create a mock
    let _m = server.mock("GET", "/hello")
      .with_status(201)
      .with_header("content-type", "text/plain")
      .with_header("x-api-key", "1234")
      .with_body("world")
      .create();

    // Any calls to GET /hello beyond this line will respond with 201, the
    // `content-type: text/plain` header and the body "world".

    // You can use `Mock::assert` to verify that your mock was called
    // m.assert();
  }
}

Use matchers to handle requests to the same endpoint in a different way:

#[cfg(test)]
mod tests {
  #[test]
  fn test_something() {
    let mut server = mockito::Server::new();

    let m1 = server.mock("GET", "/greetings")
      .match_header("content-type", "application/json")
      .match_body(mockito::Matcher::PartialJsonString(
          "{\"greeting\": \"hello\"}".to_string(),
      ))
      .with_body("hello json")
      .create();

    let m2 = server.mock("GET", "/greetings")
      .match_header("content-type", "application/text")
      .match_body(mockito::Matcher::Regex("greeting=hello".to_string()))
      .with_body("hello text")
      .create();
  }
}

Start multiple servers to simulate requests to different hosts:

#[cfg(test)]
mod tests {
  #[test]
  fn test_something() {
    let mut twitter = mockito::Server::new();
    let mut github = mockito::Server::new();

    // These mocks will be available at `twitter.url()`
    let twitter_mock = twitter.mock("GET", "/api").create();

    // These mocks will be available at `github.url()`
    let github_mock = github.mock("GET", "/api").create();
  }
}

Write async tests (make sure to use the _async methods!):

#[cfg(test)]
mod tests {
  #[tokio::test]
  async fn test_something() {
    let mut server = Server::new_async().await;
    let m1 = server.mock("GET", "/a").with_body("aaa").create_async().await;
    let m2 = server.mock("GET", "/b").with_body("bbb").create_async().await;

    let (m1, m2) = futures::join!(m1, m2);

    // You can use `Mock::assert_async` to verify that your mock was called
    // m1.assert_async().await;
    // m2.assert_async().await;
  }
}

Lifetime

Just like any Rust object, a mock is available only through its lifetime. You’ll want to assign the mocks to variables in order to extend and control their lifetime.

Avoid using the underscore matcher when creating your mocks, as in let _ = mock("GET", "/"). This will end your mock’s lifetime immediately. You can still use the underscore to prefix your variable names in an assignment, but don’t limit it to just this one character.